/*  
 *  Copyright 2006 Paul Jack.
 *
 *  This file is part of the Dex compiler suite. 
 *  
 *  Dex is free software; you can redistribute it and/or modify it
 *  under the terms of the GNU General Public License as published by the
 *  Free Software Foundation; either version 2 of the License, or (at your
 *  option) any later version.
 *  
 *  Dex is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 *  Public License for more details.
 *  
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
 */
package dex.misc;


/**
 * An object that allows new fields to be added to it at runtime.
 * This class utilizes Java's generic programming capabilities to
 * provide typesafe, random access to dynamically created fields.
 *
 * <p>With augments, a developer can allow other packages to track
 * additional state not normally 
 * 
 * <p>This pattern can be used to separate concerns in large software
 * projects.  For instance, consider a web-based accounting program
 * with a relational database backend.  The data model for that 
 * program might include classes that represent Transactions, 
 * Vendors, and so on.  The web-based presentation code of the system
 * might need draw a table of color-coded transactions, where the
 * color of each transaction is determined by characteristics of the
 * entire set.  One could add a <code>color</code> field to the 
 * <code>Transaction</code> class, but that binds the data model
 * to the presentation layer.  A purely back-end operation (such as
 * a nightly batch job) would have no need for the color field, but
 * would have to include the <code>Color</code> class, and possibly
 * the entire presentation layer, in its source tree.
 * 
 * <p>To keep concerns separate, a developer would usually have the
 * presentation layer keep a <code>Map</code> from transactions to
 * colors.  That's slow, however, especially if the set of transactions
 * that determine the colors were large.
 * 
 * <p>With augments, the data model developer could allow other packages
 * to extend the state of the model objects without injected dependencies.
 * 
 * <p>First, the data model developer would define their <code>Transaction</code>
 * class to extend <code>Augmented</code>:
 * 
 * <pre>
 * package datamodel;
 * 
 * public class Transaction extends Augmented&lt;Transaction&gt; {
 * 
 *     // ...
 *  
 * }
 * </pre>
 *
 * <p>Then the presentation developer could define a new augment in the 
 * presentation code:
 * 
 * <pre>
 * package presentation;
 * 
 * public class ColorAlgorithm {
 * 
 *     final public static Augment&lt;Transaction,Color&gt; COLOR 
 *      = Augment.create(Transaction.class, Color.class);
 *
 *     public static void setColors(Transaction[] transactions) {
 *         for (Transaction t: transactions) {
 *             if (t.get(COLOR) == null) {
 *                 Color color = pickColor(transactions, t);
 *                 t.set(COLOR, color);
 *             }
 *         }
 *     }
 * }
 * </pre>
 * 
 * <p>The compiler ensures that <code>get</code> and <code>set</code>
 * 
 * <p>The <code>get</code> and <code>set</code> methods are O(1) operations, even
 * in the worst case.  In fact performance testing has shown that using
 * <code>get</code> and <code>set</code> perform similarly to simple access
 * to an actual Java instance field.
 * 
 * 
 * 
 */
public abstract class Augmented<Family> {


	/**
	 * The extended values.
	 */
	private Object[] augmentValues;
	
	
	public Augmented() {
		augmentValues = new Object[Augment.getExtensionCount(getClass())]; 
	}
	

	/**
	 * Retrieves a value of the given augment.
	 * 
	 * @param <T>      the type of the augmented field
	 * @param augment  the augmented field whose value to retrieve
	 * @return         the value of that augmented field
	 */
	@SuppressWarnings("unchecked")
	public <T> T get(Augment<? extends Family,T> augment) {
		int index = augment.index;
		if (augmentValues.length <= index) {
			return null;
		}
		return (T)augmentValues[augment.index];
	}
	
	
	/**
	 * Sets the value of the given augment.
	 * 
	 * @param <T>      the type of the augmented field
	 * @param augment  the augmented field whose value to set
	 * @param value    the new value for that field
	 */
	public <T> void set(Augment<? extends Family,T> augment, T value) {
		int index = augment.index;
		if (augmentValues.length <= index) {
			Object[] temp = augmentValues;
			augmentValues = new Object[index + 1];
			System.arraycopy(temp, 0, augmentValues, 0, temp.length);
		}
		augmentValues[index] = value;
	}
	
}
